beancount accounting

Beancount Accounting Skill Beancount is a plain-text double-entry accounting system. This skill provides expertise for creating, editing, and querying beancount files. Core Concepts Double-Entry Accounting Every transaction must balance to zero. Money flows between accounts: Debits increase Assets/Expenses, decrease Liabilities/Income/Equity Credits decrease Assets/Expenses, increase Liabilities/Income/Equity Five Account Types Type Purpose Normal Balance Assets What you own (bank accounts, investments) Positive Liabilities What you owe (credit cards, loans) Negative Income Money coming in (salary, interest) Negative Expenses Money going out (food, rent) Positive Equity Net worth, opening balances Negative Account Naming Use colon-separated hierarchical names starting with capital letters: Type:Country:Institution:Account:SubAccount Examples: Assets:Checking:Centennial:Joint Liabilities:Card:Chase:Sapphire Expenses:Food:Groceries Income:Salary:Employer Transaction Syntax Basic Format YYYY-MM-DD flag "Payee" "Narration" Account1 Amount Currency Account2 Amount Currency ; optional comment Flags * - Cleared/completed transaction ! - Pending/needs review Examples Simple expense: 2026-01-03 * "Starbucks" "Morning coffee" Expenses:Food:Coffee 5.75 USD Liabilities:Card:Chase:Sapphire Paycheck with multiple postings: 2026-01-15 * "Employer" "Bi-weekly salary" Assets:Checking:Main 3500.00 USD Expenses:Taxes:Federal 800.00 USD Expenses:Taxes:State 200.00 USD Expenses:Insurance:Health 150.00 USD Income:Salary -4650.00 USD Transfer between accounts: 2026-01-10 * "Transfer to savings" Assets:Savings:Ally 500.00 USD Assets:Checking:Main -500.00 USD Amount Interpolation One posting amount can be omitted - beancount calculates it: 2026-01-03 * "Grocery Store" "Weekly groceries" Expenses:Food:Groceries 125.43 USD Assets:Checking:Main ; Amount calculated as -125.43 USD Essential Directives open / close Declare account lifecycle: 2026-01-01 open Assets:Checking:Main USD 2028-12-31 close Assets:Checking:Main balance Assert account balance at start of day (catches errors): 2026-01-31 balance Assets:Checking:Main 4583.84 USD pad Auto-generate balancing entry between two dates: 2026-01-01 pad Assets:Checking:Main Equity:Opening-Balances 2026-01-02 balance Assets:Checking:Main 4583.84 USD include Split files for organization: include "2026-01.beancount" include "accounts.beancount" option Configure beancount behavior: option "title" "Personal Finances" option "operating_currency" "USD" Metadata and Tags Metadata Attach key-value pairs to directives or postings: 2026-01-03 * "Amazon" "Office supplies" order-id: "123-456-789" Expenses:Office 45.00 USD category: "equipment" Liabilities:Card:Chase Tags and Links Group related transactions: 2026-01-15 * "Hotel" "Conference lodging" #work-travel #conference-2026 Expenses:Travel:Lodging 299.00 USD Liabilities:Card:Chase 2026-02-01 * "Expense Report" "Reimbursement" ^conference-2026 Assets:Checking:Main 299.00 USD Income:Reimbursements BQL Queries Beancount Query Language (BQL) provides SQL-like queries. Run with bean-query : bean-query finances/2026.beancount "SELECT account, sum(position) WHERE account ~ 'Expenses' GROUP BY 1" Common Queries Account balance: SELECT account , sum ( position ) WHERE account ~ 'Assets:Checking' GROUP BY 1 Monthly expenses by category: SELECT MONTH ( date ) , account , sum ( position ) WHERE account ~ 'Expenses' AND year = 2026 GROUP BY 1 , 2 ORDER BY 1 , 2 Transactions for an account: SELECT date , narration , payee , position , balance WHERE account = 'Assets:Checking:Centennial:Joint' ORDER BY date Key BQL Functions Function Purpose SUM(position) Aggregate amounts YEAR(date) , MONTH(date) Extract date parts COST(position) Get cost basis account ~ 'pattern' Regex match account Working with Beancount Files Reading Files Before editing, read the beancount file to understand: Existing account structure Naming conventions used Transaction patterns Include file organization Adding Transactions Match existing account names exactly Use consistent payee/narration style Ensure transaction balances to zero Add to chronologically appropriate location or include file Validation Run bean-check to validate syntax: bean-check finances/2026.beancount Common Patterns Credit card payment: 2026-01-25 * "Chase" "Credit card payment" Liabilities:Card:Chase:Sapphire 500.00 USD Assets:Checking:Main -500.00 USD Investment purchase with cost basis: 2026-01-20 * "Fidelity" "Buy index fund" Assets:Investments:Fidelity:FXAIX 10 FXAIX {150.00 USD} Assets:Investments:Fidelity:Cash -1500.00 USD Mortgage payment breakdown: 2026-01-01 * "Rocket Mortgage" "Monthly mortgage" Liabilities:Loan:RocketMortgage 800.00 USD ; Principal Expenses:Housing:Interest 900.00 USD ; Interest Expenses:Housing:Escrow 300.00 USD ; Escrow Assets:Checking:Main -2000.00 USD Best Practices File Organization Use include to split by month or category Keep account definitions in main file Add transactions to appropriate include files Account Hierarchy Be consistent with naming depth Use specific subcategories for visibility Group related accounts logically Balance Assertions Add monthly balance assertions for bank accounts Reconcile against actual statements Catches data entry errors early Error Prevention Always run bean-check after edits Use balance assertions frequently Keep transactions in chronological order Additional Resources Reference Files For detailed syntax and patterns, consult: references/syntax.md - Complete directive reference with all options references/bql.md - Full BQL query language documentation references/examples.md - Common transaction patterns and workflows Command Line Tools Command Purpose bean-check file.beancount Validate syntax bean-query file.beancount "QUERY" Run BQL query bean-report file.beancount balances Balance report bean-web file.beancount Web interface